home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 February: Tool Chest / Apple Developer CD Series Tool Chest February 1996 (Apple Computer)(1996).iso / Sample Code / AOCE Sample Code / PowerTalk Access Modules / Sample SMSAM / SampleSMSAM Source / CoreGateway / Letter.h < prev    next >
Encoding:
C/C++ Source or Header  |  1995-07-28  |  8.2 KB  |  180 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        Letter.h
  3.  
  4.     Copyright:    © 1991-1994 by Apple Computer, Inc.
  5.                 All rights reserved.
  6.  
  7.     Part of the AOCE Sample SMSAM Package.  Consult the license
  8.     which came with this software for your specific legal rights.
  9.  
  10. */
  11.  
  12.  
  13.  
  14. #ifndef __LETTER__
  15. #define __LETTER__
  16.  
  17. #ifndef __BLJSTANDARDINCLUDES__
  18. #include "BLJStandardIncludes.h"
  19. #endif
  20.  
  21. #ifndef __COREGATEWAYTYPES__
  22. #include "CoreGatewayTypes.h"
  23. #endif
  24.  
  25. #ifndef __RECIPIENT__
  26. #include "Recipient.h"
  27. #endif
  28.  
  29. class ostream;
  30. class TVirtualFolder;
  31.  
  32. /***********************************|****************************************/
  33.  
  34. class TLetter : public THandleObject 
  35. {
  36. public:
  37.     virtual ~TLetter();
  38.  
  39. //
  40. //    LETTER HEADER METHODS
  41. //    =====================
  42. //
  43.     //    LetterID Methods:  Each letter should support the GetLetterID method.  A LetterID
  44.     //    is a key which MUST uniquely identify a letter.  A letter does not need to have
  45.     //    a letterID.  A ReplyID may exists in a letter.  If it does, then (by convention)
  46.     //    this letter is a reply to a previous letter and the replyID is the letterID of
  47.     //    the original letter.  Currently the conversationID does not have a well accepted
  48.     //    meaning.
  49.     virtual Boolean GetLetterID (BLJLetterID&) const = 0;
  50.     virtual Boolean GetReplyID (BLJLetterID&) const = 0;
  51.     virtual Boolean GetConversationID (BLJLetterID&) const = 0;
  52.  
  53.     //    The time that the letter was 'sent'.  This should be as close to the time that 
  54.     //    the user actually sent the letter as possible, but should be 'authenticated' in
  55.     //    some way which the sender should not be able to 'fake'.  Typically, in a system
  56.     //    where server machines accept and route mail, this will be the time the letter was
  57.     //    received from the user onto the first server.  In some cases, this time may differ
  58.     //    signifigantly from the time when the user actually sent the letter.  If no time
  59.     //    is given in the letter, then the receiving mail gateway may insert the current time
  60.     //    or do something else if a send time is necessary.
  61.     virtual Boolean GetSendTimeStamp (BLJTime& sendTime) const = 0;
  62.  
  63.     //    Letters may contain a priority.  There is no guarentee that any mail gateway
  64.     //    will respect the priority in a letter.
  65.     enum LetterPriority { noPriority, lowPriority, highPriority };
  66.     virtual Boolean GetLetterPriority (LetterPriority& priority) const = 0;
  67.  
  68.     //    A letter should contain a subject, but it does not have to have one.  
  69.     virtual Boolean GetSubject (TRString& subject) const = 0;
  70.  
  71.     //    Letters may be automatically forwarded or automatically replied to by some
  72.     //    destination mail systems.  If this is supported by the originating mail
  73.     //    system, then these functions will return the appropriate booleans indicating
  74.     //    whether this has happened for this letter.  Similarly, some letters can carry
  75.     //    attributes controlling their distribution.  If these attributes are present,
  76.     //    the Can… methods indicate which attribute values exist in this letter.
  77.     virtual Boolean IsLetterAutoForwarded (Boolean& yesItIs) const = 0;
  78.     virtual Boolean IsLetterAutoReply (Boolean& yesItIs) const = 0;
  79.     virtual Boolean CanLetterBeAutoForwarded (Boolean& yesItCan) const = 0;
  80.     virtual    Boolean    LetterIsCompleted ();
  81.     
  82. //
  83. //    LETTER RECIPIENTS
  84. //    =================
  85. //
  86.     //    A letter MUST contain at least one recipient.  Recipients fall into one of
  87.     //    several types: fromRecipient, toRecipient, ccRecipient, and bccRecipient.
  88.     //    Each of these recipients is distinct.  Each recipient represents a singe
  89.     //    'address', which may represent a single user or a group of users; and each
  90.     //    recipient is one for which the half gateway receiving this letter is either
  91.     //    responsible for delivering a letter to or not.
  92.     virtual unsigned short GetRecipientCount(RecipientTypeSet recipientType) const = 0;
  93.     virtual TRecipient* GetRecipient (RecipientTypeSet recipientType, unsigned short index) const = 0;
  94.  
  95. //
  96. //    RECIPIENT REPORTS METHODS
  97. //    =========================
  98. //
  99.     //    These functions deal with reporting on the 'status' for an individual recipient.
  100.     //    The recieving mail system should use these functions to report back the status for those
  101.     //    recipients for which status was requested (see the calls below).  Each recipient for which
  102.     //    the destination half gateway is responsible should be reported on.
  103.     virtual Boolean GetRecipientStatus(RecipientTypeSet, unsigned short index, RecipientStatusSet&) const = 0;
  104.     virtual Boolean SetRecipientStatus(RecipientTypeSet, unsigned short index, RecipientStatusSet) = 0;
  105.     
  106.     //    GetUnknownRecipientCount() is a short-hand way of determining the number of recipients
  107.     //    with the status cUnknown for which the destination half gateway is responsible.  This is
  108.     //    important because when this value falls to zero, all recipients which the half gateway
  109.     //    was responsible for have been discharged, and so the destination half gateway does not
  110.     //    need to keep track of this letter any longer.
  111.     virtual unsigned short GetUnknownRecipientCount() const = 0;
  112.  
  113.     //    These routines return booleans related to the reports requested    about this letter.
  114.     virtual Boolean DeliveryReceiptRequested(Boolean &yesItIs) const = 0;
  115.     virtual Boolean NonDeliveryReportRequested (Boolean& yesItIs) const = 0;
  116.  
  117. //
  118. //    LETTER CONTENT METHODS
  119. //    ======================
  120. //        
  121.     //    A letter's content consists of several parts: First, there are a sequence
  122.     //    of segments, numbered from 1… GetSegmentCount().  Each segment is a certain
  123.     //    type of data, indicated by the blockType returned by GetSegmentInfo().  Certain
  124.     //    types have a well known format - 'TEXT' represents simple ASCII text, 'stxt' is
  125.     //    styled text, 'snd ' is a sampled sound, and there are others which are not described
  126.     //    herein.  A half gateway should support (at the minimum) the 'TEXT' and 'stxt' type.
  127.     //    A letter may contain no segment blocks.
  128.     //    These deal with the content of the message
  129.     virtual unsigned long             GetContentTypeCount ( ) const = 0;
  130.     virtual OSType                     GetContentType ( unsigned long i ) const = 0;
  131.  
  132.     virtual unsigned long             GetSegmentCount( OSType contentType ) const = 0;
  133.     virtual Boolean                 GetSegmentData( OSType contentType, unsigned long index, unsigned long offset,void *data, long& maximumDataSize ) const = 0;
  134.     virtual Boolean                 GetSegmentInfo( OSType contentType, unsigned long index, BLJLetterBlockType& blockType, long& blockLength ) const = 0;
  135.  
  136.     //    A letter may also contain any number of 'enclosed' Macintosh files, in a hierarchy
  137.     //    of files and folders.  If a letter contains enclosures, then a TVirtualFolder will
  138.     //    be returned, and this folder will contain the files and folders which are 'enclosed'
  139.     //    in this letter.  This 'magic' folder which is returned is not itself in the letter.
  140.     //    If this letter contains no enclosures, then GetEnclosuresFolder() will return nil.
  141.     virtual TVirtualFolder* GetEnclosuresFolder() const = 0;
  142.  
  143.     //    Each letter may contain a number of 'nested' letters.  GetNestedLetterCount() will
  144.     //    return the count of the letters available, and GetNestedLetter(i) will return the
  145.     //    i-th nested letter at the current level.  Note that although all of the letter
  146.     //    methods will return data for the nested letter, nested letters are NOT exactly the
  147.     //    same as the 'top level' letter.  The recipients in nested letters are never recipients
  148.     //    for which the destination half gateway could be responsible for.
  149.     virtual unsigned short GetNestedLetterCount() const = 0;
  150.     virtual TLetter* GetNestedLetter(unsigned short index) const = 0;
  151.  
  152. //
  153. //    MISCELLANEOUS METHODS
  154. //    =====================
  155. //
  156.     //    A letter (obviously) occupies a chunk of memory and other resources.  Some of this
  157.     //    usage may be for convinience or speed reasons.  The Minimize() method may 'free' up
  158.     //    some of this memory usage.  This method may do nothing.
  159.     virtual void Minimize();
  160.  
  161. //
  162. //    DEBUGGING METHODS
  163. //    =================
  164. //
  165.     virtual ostream& Describe(ostream& s) const;    // Display info about object, calls DescribeSubclass()
  166.     virtual ostream& DescribeSubclass(ostream& s) const; // Display specific info about object, should override
  167.     virtual ostream&                 operator >> ( ostream& ) const;
  168.  
  169. /***********************************|****************************************/
  170.     
  171.     static Boolean                    SetAllUnknownRecipientStatus ( TLetter* letter, const RecipientStatusSet& status );
  172.  
  173. protected:
  174.     TLetter();            //    default constructor
  175. };
  176.  
  177. /***********************************|****************************************/
  178.  
  179. #endif    // __LETTER__
  180.